/*
 *  Copyright 2011 yura.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *       http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *  under the License.
 */

package org.opu.vcforms.transform_t2d.content;

/**
 *
 *  Content is like double array or like a set of maps. Where map
 * keys is array headers and values is value.
 *
 * <pre>
 * -------------------
 * |id| name | value |
 * -------------------
 * | 1| n1   | v1    |
 * | 2| n2   | v2    |
 * -------------------
 * </pre>
 *
 * When presenting as an array, it`s will be
 * <pre>
 *  arr[0][0] = 1
 *  arr[0][1] = n1
 *  arr[0][2] = v1
 *  arr[1][0] = 2
 *  arr[1][1] = n2
 *  arr[1][2] = v2
 * </pre>
 *
 * When presenting as set of maps, it`s will be
 * <pre>
 *  Set {
 *    - Map(header, value){
 *          (id, 1)
 *          (name, n1)
 *          (value, v1)
 *      }
 * 
 *    - Map(header, value){
 *          (id, 2)
 *          (name, n2)
 *          (value, v2)
 *      }
 *  }
 * </pre>
 *
 * For the universality of all representated as set. And you moved
 * through content like through iterator of iterators (iterator of
 * rows, and iterator of cells in each row).
 *
 * @author yura
 */
public interface ContentAPI {

    /**
     *  Return parent content where current content is.
     * The value can be null, if current content is top level.
     * @return parent content where current content is
     */
    public ContentAPI getParent();

    /**
     *  Get value of cell by it header name in current rows.
     * @param name header name
     * @return value of cell if it posible, in ather way it returned null.
     * It`s also can return empty string if it duti call.
     */
    public String get(String name);

    /**
     *  Return value of current cell in current row, and do step in row.
     * But not in rows, sow if it last cell you needed to call method
     * {@link #step() }
     * @return value of current cell in current row.
     */
    public String next();

    /**
     * Returns <tt>true</tt> if the <b>cell</b> iteration has more elements.
     * (In other words, returns <tt>true</tt> if <tt>next</tt> would
     * return an element rather than throwing an exception.)
     *
     * @return <tt>true</tt> if the iterator has more cells.
     */
    public boolean hasNext();

    /**
     *  Do iteration in rows, and retun true if availabel next row.
     * @return true if availabel next row.
     */
    public boolean step();

    /**
     * Returns <tt>true</tt> if the <b>row</b> iteration has more elements.
     * (In other words, returns <tt>true</tt> if <tt>next</tt> would
     * return an element rather than throwing an exception.)
     *
     * @return <tt>true</tt> if the iterator has more cells.
     */
    public boolean hasStep();

    /**
     * Returns <tt>true</tt> if the current <b>cell</b> iteration is not null.
     * (In other words, returns <tt>true</tt> if last call of <tt>next</tt>
     * would return an element rather than throwing an exception.)
     *
     * @return <tt>true</tt> if the iterator of cells not null.
     */
    public boolean hasData();

    /**
     *  Return last value that war available (after call
     * {@link #get(java.lang.String)} or {@link #next()})
     * @return last value that war available
     */
    public String last();

    /**
     *  Return current step: start from 1.
     * @return current step: start from 1.
     */
    public int iteration();

}
